<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>38.7. Zend_Service_Nirvanix</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="prev" href="zend.service.flickr.html" title="38.6. Zend_Service_Flickr">
<link rel="next" href="zend.service.simpy.html" title="38.8. Zend_Service_Simpy">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.introduction" title="38.7.1. Introduction">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.registering" title="38.7.2. Registering with Nirvanix">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.apiDocumentation" title="38.7.3. API Documentation">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.features" title="38.7.4. Features">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.storing-your-first" title="38.7.5. Getting Started">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.understanding-proxy" title="38.7.6. Understanding the Proxy">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.examining-results" title="38.7.7. Examining Results">
<link rel="subsection" href="zend.service.nirvanix.html#zend.service.nirvanix.handling-errors" title="38.7.8. Handling Errors">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">38.7. Zend_Service_Nirvanix</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.service.flickr.html">Prev</a> </td>
<th width="60%" align="center">Chapter 38. Zend_Service</th>
<td width="20%" align="right"> <a accesskey="n" href="zend.service.simpy.html">Next</a>
</td>
</tr>
</table></div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.service.nirvanix"></a>38.7. Zend_Service_Nirvanix</h2></div></div></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.introduction"></a>38.7.1. Introduction</h3></div></div></div>
<p>
            Nirvanix provides an Internet Media File System (IMFS), an
            Internet storage service that allows applications to upload, store and
            organize files and subsequently access them using a standard Web
            Services interface. An IMFS is distributed clustered file system,
            accessed over the Internet, and optimized for dealing with media files
            (audio, video, etc). The goal of an IMFS is to provide massive
            scalability to deal with the challenges of media storage growth, with
            guaranteed access and availability regardless of time and location.
            Finally, an IMFS gives applications the ability to access data
            securely, without the large fixed costs associated with acquiring and
            maintaining physical storage assets.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.registering"></a>38.7.2. Registering with Nirvanix</h3></div></div></div>
<p>
            Before you can get started with <code class="code">Zend_Service_Nirvanix</code>, you must first
            register for an account.  Please see the 
            <a href="http://www.nirvanix.com/gettingStarted.aspx" target="_top">Getting Started</a>
            page on the Nirvanix website for more information.
        </p>
<p>
            After registering, you will receive a Username, Password, and 
            Application Key.  All three are required to use <code class="code">Zend_Service_Nirvanix</code>.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.apiDocumentation"></a>38.7.3. API Documentation</h3></div></div></div>
<p>
            Access to the Nirvanix IMFS is available through both SOAP and a faster 
            REST service.  <code class="code">Zend_Service_Nirvanix</code> provides a 
            relatively thin PHP 5 wrapper around the REST service.
        </p>
<p>
            <code class="code">Zend_Service_Nirvanix</code> aims to make using the Nirvanix REST service
            easier but understanding the service itself is still essential to be successful
            with Nirvanix.  
        </p>
<p>
            The <a href="http://developer.nirvanix.com/sitefiles/1000/API.html" target="_top">Nirvanix API Documentation</a>
            provides an overview as well as detailed information using the
            service.  Please familiarize yourself with this document and refer back to it
            as you use <code class="code">Zend_Service_Nirvanix</code>.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.features"></a>38.7.4. Features</h3></div></div></div>
<p>
            Nirvanix's REST service can be used effectively with PHP using the 
            <a href="http://www.php.net/simplexml" target="_top">SimpleXML</a>
            extension and <code class="code">Zend_Http_Client</code> alone. However, using it this way
            is somewhat inconvenient due to repetitive operations like passing the
            session token on every request and repeatedly checking the response body for
            error codes.  
        </p>
<p>
            <code class="code">Zend_Service_Nirvanix</code> provides the following functionality:

            </p>
<div class="itemizedlist"><ul type="disc">
<li><p>
                        A single point for configuring your Nirvanix authentication
                        credentials that can be used across the Nirvanix namespaces.
                    </p></li>
<li><p>
                        A proxy object that is more convenient to use than an HTTP client
                        alone, mostly removing the need to manually construct HTTP POST
                        requests to access the REST service.
                    </p></li>
<li><p>
                        A response wrapper that parses each response body and throws an
                        exception if an error occurred, alleviating the need to repeatedly 
                        check the success of many commands.
                    </p></li>
<li><p>
                        Additional convenience methods for some of the more common operations.
                    </p></li>
</ul></div>
<p>
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.storing-your-first"></a>38.7.5. Getting Started</h3></div></div></div>
<p>
            Once you have registered with Nirvanix, you're ready to store your first
            file on the IMFS.  The most common operations that you will need to do 
            on the IMFS are creating a new file, downloading an existing file, and
            deleting a file.  <code class="code">Zend_Service_Nirvanix</code> provides convenience
            methods for these three operations.
        </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Service/Nirvanix.php';        

$auth = array('username' =&gt; 'your-username',
              'password' =&gt; 'your-password',
              'appKey'   =&gt; 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix-&gt;getService('IMFS');

$imfs-&gt;putContents('/foo.txt', 'contents to store');

echo $imfs-&gt;getContents('/foo.txt');

$imfs-&gt;unlink('/foo.txt');
        </pre>
<p>
            The first step to using <code class="code">Zend_Service_Nirvanix</code> is always
            to authenticate against the service. This is done by passing your
            credentials to the <code class="code">Zend_Service_Nirvanix</code> constructor
            above. The associative array is passed directly to Nirvanix as POST
            parameters.
        </p>
<p>
            Nirvanix divides its web services into 
            <a href="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999879" target="_top">namespaces</a>.  
            Each namespace encapsulates a group of related operations. After getting
            an instance of <code class="code">Zend_Service_Nirvanix</code>, call the
            <code class="code">getService()</code> method to create a proxy for the namespace
            you want to use. Above, a proxy for the <code class="code">IMFS</code> namespace is created.
        </p>
<p>
            After you have a proxy for the namespace you want to use, call methods on it.
            The proxy will allow you to use any command available on the REST API.  The
            proxy may also make convenience methods available, which wrap web service
            commands.  The example above shows using the IMFS convenience methods to create a
            new file, retrieve and display that file, and finally delete the file.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.understanding-proxy"></a>38.7.6. Understanding the Proxy</h3></div></div></div>
<p>
            In the previous example, we used the <code class="code">getService()</code> method to return
            a proxy object to the <code class="code">IMFS</code> namespace.  The proxy object allows
            you to use the Nirvanix REST service in a way that's closer to making a normal
            PHP method call, as opposed to constructing your own HTTP request objects.
        </p>
<p>
            A proxy object may provide convenience methods.  These are methods that the
            <code class="code">Zend_Service_Nirvanix</code> provides to simplify the use of 
            the Nirvanix web services.  In the previous example, the methods 
            <code class="code">putContents()</code>, <code class="code">getContents()</code>, and <code class="code">unlink()</code>
            do not have direct equivalents in the REST API.  They are convenience methods 
            provided by <code class="code">Zend_Service_Nirvanix</code> that abstract more complicated
            operations on the REST API.
        </p>
<p>
            For all other method calls to the proxy object, the proxy will dynamically
            convert the method call to the equivalent HTTP POST request to the REST API.
            It does this by using the method name as the API command, and an associative
            array in the first argument as the POST parameters.  
        </p>
<p>
            Let's say you want to call the REST API method 
            <a href="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999923" target="_top">RenameFile</a>,
            which does not have a convenience method in <code class="code">Zend_Service_Nirvanix</code>:
        </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Service/Nirvanix.php';        

$auth = array('username' =&gt; 'your-username',
              'password' =&gt; 'your-password',
              'appKey'   =&gt; 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix-&gt;getService('IMFS');

$result = $imfs-&gt;renameFile(array('filePath' =&gt; '/path/to/foo.txt',
                                  'newFileName' =&gt; 'bar.txt'));
        </pre>
<p>
            Above, a proxy for the <code class="code">IMFS</code> namespace is created.  A method, 
            <code class="code">renameFile()</code>, is then called on the proxy.  This method does not
            exist as a convenience method in the PHP code, so it is trapped by 
            <code class="code">__call()</code> and converted into a POST request to the REST API where
            the associative array is used as the POST parameters.
        </p>
<p>
            Notice in the Nirvanix API documentation that <code class="code">sessionToken</code> is required
            for this method but we did not give it to the proxy object.  It is added 
            automatically for your convenience.
        </p>
<p>
            The result of this operation will either be a <code class="code">Zend_Service_Nirvanix_Response</code>
            object wrapping the XML returned by Nirvanix, or a <code class="code">Zend_Service_Nirvanix_Exception</code>
            if an error occurred.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.examining-results"></a>38.7.7. Examining Results</h3></div></div></div>
<p>
            The Nirvanix REST API always returns its results in XML.  <code class="code">Zend_Service_Nirvanix</code>
            parses this XML with the <code class="code">SimpleXML</code> extension and then decorates
            the resulting <code class="code">SimpleXMLElement</code> with a <code class="code">Zend_Service_Nirvanix_Response</code>
            object.  
        </p>
<p>
            The simplest way to examine a result from the service is to use the
            built-in PHP functions like <code class="code">print_r()</code>:
        </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Service/Nirvanix.php';        

$auth = array('username' =&gt; 'your-username',
              'password' =&gt; 'your-password',
              'appKey'   =&gt; 'your-app-key');

$nirvanix = new Zend_Service_Nirvanix($auth);
$imfs = $nirvanix-&gt;getService('IMFS');

$result = $imfs-&gt;putContents('/foo.txt', 'fourteen bytes');
print_r($result);
?&gt;


Zend_Service_Nirvanix_Response Object
(
    [_sxml:protected] =&gt; SimpleXMLElement Object
        (
            [ResponseCode] =&gt; 0
            [FilesUploaded] =&gt; 1
            [BytesUploaded] =&gt; 14
        ))
        </pre>
<p>
            You can access any property or method of the decorated <code class="code">SimpleXMLElement</code>.
            In the above example, <code class="code">$result-&gt;BytesUploaded</code> could be used to see the
            number of bytes received.  Should you want to access the <code class="code">SimpleXMLElement</code>
            directly, just use <code class="code">$result-&gt;getSxml()</code>.
        </p>
<p>
            The most common response from Nirvanix is success (<code class="code">ResponseCode</code> of zero).  
            It is not normally necessary to check <code class="code">ResponseCode</code> because any non-zero
            result will throw a <code class="code">Zend_Service_Nirvanix_Exception</code>.  See the next
            section on handling errors.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.service.nirvanix.handling-errors"></a>38.7.8. Handling Errors</h3></div></div></div>
<p>
            When using Nirvanix, it's important to anticipate errors that can be returned 
            by the service and handle them appropriately.  
        </p>
<p>
            All operations against the REST service result in an XML return payload that 
            contains a <code class="code">ResponseCode</code> element, such as the following example:
        </p>
<pre class="programlisting">
&lt;Response&gt;
   &lt;ResponseCode&gt;0&lt;/ResponseCode&gt;
&lt;/Response&gt;
        </pre>
<p>
            When the <code class="code">ResponseCode</code> is zero such as in the example
            above, the operation was successful. When the operation is not
            successful, the <code class="code">ResponseCode</code> is non-zero and an
            <code class="code">ErrorMessage</code> element should be present.
        </p>
<p>
            To alleviate the need to repeatedly check if the <code class="code">ResponseCode</code>
            is non-zero, <code class="code">Zend_Service_Nirvanix</code> automatically checks each response 
            returned by Nirvanix.  If the <code class="code">ResponseCode</code> indicates an 
            error, a <code class="code">Zend_Service_Nirvanix_Exception</code> will be thrown.
        </p>
<pre class="programlisting">&lt;?php
require_once 'Zend/Service/Nirvanix.php';        
        
$auth = array('username' =&gt; 'your-username',
              'password' =&gt; 'your-password',
              'appKey'   =&gt; 'your-app-key');
$nirvanix = new Zend_Service_Nirvanix($auth);

try {

  $imfs = $nirvanix-&gt;getService('IMFS');
  $imfs-&gt;unlink('/a-nonexistant-path');

} catch (Zend_Service_Nirvanix_Exception $e) {
  echo $e-&gt;getMessage() . "\n";
  echo $e-&gt;getCode();
}
        </pre>
<p>
            In the example above, <code class="code">unlink()</code> is a convenience method that wraps the
            <code class="code">DeleteFiles</code> command on the REST API.  The <code class="code">filePath</code> parameter required by the
            <a href="http://developer.nirvanix.com/sitefiles/1000/API.html#_Toc175999918" target="_top">DeleteFiles</a>
            command contains a path that does not exist.  This will result in a 
            <code class="code">Zend_Service_Nirvanix</code> exception being thrown with the message
            "Invalid path" and code 70005.
        </p>
<p>
            The <a href="http://developer.nirvanix.com/sitefiles/1000/API.html" target="_top">Nirvanix
            API Documentation</a> describes the errors associated with each command.  Depending
            on your needs, you may wrap each command in a <code class="code">try</code> block or 
            wrap many commands in the same <code class="code">try</code> block for convenience.  
        </p>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.service.flickr.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="zend.service.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="zend.service.simpy.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">38.6. Zend_Service_Flickr </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 38.8. Zend_Service_Simpy</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
